workspace: last-active frontmatter + handoff skill, bump to v0.2.0 - #255

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/workspace/tests/test_recent_projects.py`:
- Around line 61-183: Add a negative test class alongside TestFallbackToMtime
that writes a project with a malformed last_active value and an older CLAUDE.md
mtime, plus a project without last_active and a newer mtime. Run the existing
run_hook flow and assert both projects remain in the systemMessage, with the
newer mtime-only project ordered before the malformed-date project, confirming
fallback to newest_mtime().

---

Nitpick comments:
In `@docs/superpowers/plans/2026-08-04-last-active-frontmatter.md`:
- Around line 270-312: The plan’s documented `sort_source` contract does not
match the shipped `collect_projects` implementation. Update the plan’s
`collect_projects` example and Interfaces description to remove the
`sort_source` field and its testability claim, unless the final implementation
is intentionally expected to expose it; keep the documentation consistent with
the reviewed script.

In `@plugins/workspace/scripts/recent-projects.py`:
- Around line 91-106: Rename the `"mtime"` field created in `collect_projects()`
to `"sort_ts"` (or another clearly sort-oriented name), since it stores both
file modification times and last-active-derived timestamps. Update every
consumer of the collected entry field to use the renamed key while preserving
the existing sorting behavior.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/workspace/.claude-plugin/plugin.json`:
- Line 5: Update the workspace entry in the marketplace configuration to version
0.2.0 so it matches the version declared by the plugin manifest.

In `@plugins/workspace/scripts/handoff.py`:
- Around line 150-155: Update the project validation around project_dir to
reject absolute project names and any path containing .. components, then
canonicalize the candidate path and confirm it remains within the canonical root
/ "projects" directory before allowing the handoff. Preserve the existing error
response for invalid or nonexistent projects.
- Line 56: Resolve the Ruff findings by adding narrow, reasoned noqa annotations
without changing behavior: at plugins/workspace/scripts/handoff.py:56 suppress
S606 for the fixed Python executable and script; at
plugins/workspace/scripts/handoff.py:226 suppress BLE001 using the existing
SessionStart boundary rationale; and at
plugins/workspace/tests/test_handoff.py:30-34, 44-48, and 250-253 suppress S603
for each controlled test subprocess.
- Around line 89-90: Update the marker deletion flow around unlink_quietly so it
returns whether removal succeeded, and have the caller return None when the
consumed marker cannot be removed. Preserve the marker return only after
successful deletion to maintain the single-use contract.
- Around line 110-112: Update the load_files validation before the return in the
data-loading flow to require both a list value and string type for every
element. Treat any non-list or mixed/non-string list as the invalid marker so
the existing fallback path runs and build_directive() never receives invalid
values; preserve valid lists of strings unchanged.
- Around line 158-165: Constrain checkpoint load paths to the project directory:
in plugins/workspace/scripts/handoff.py lines 158-165, reject absolute paths and
any .. components when constructing load_files, and resolve plus revalidate each
marker path beneath P.dir immediately before the Read tool uses it. Update the
corresponding path-handling guidance in
plugins/workspace/skills/checkpoint/SKILL.md lines 48-60 and
plugins/workspace/skills/resume-project/SKILL.md lines 146-154 to require the
same project-directory validation.

In `@plugins/workspace/skills/checkpoint/SKILL.md`:
- Around line 1-5: Update the checkpoint skill frontmatter to use a
colon-namespaced <domain>:<action> name and add the minimal allowed-tools
declaration for this workflow, including Skill and Bash; preserve the existing
description, argument hint, and invocation setting.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/workspace/scripts/handoff.py`:
- Around line 81-90: Update the marker handling flow around the
path.is_file/read_text logic to atomically rename handoff.json to a unique
claimed filename in the same directory before reading; only the process that
wins the rename should parse and emit the directive, and the claimed file must
be removed in a finally block. Add a concurrent read regression test in
test_handoff.py asserting exactly one process emits “Checkpoint handoff
pending.”
- Around line 168-171: Harden the marker-write flow around marker_path by
canonicalizing and validating the workspace path, rejecting traversal and
symlinked .claude or handoff.json components before writing. Replace
mkdir/write_text with no-follow directory and file operations that cannot follow
symlinks, and add a regression test covering redirected marker writes.

In `@plugins/workspace/tests/test_recent_projects.py`:
- Line 29: Add narrow `# noqa: S603` annotations to the `subprocess.run` calls
at the two reported locations in `test_recent_projects.py`, documenting that
each is a controlled repository-local test boundary using `sys.executable`
without a shell. Do not disable S603 globally or alter the subprocess behavior.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/workspace/scripts/resume-project.py`:
- Around line 111-126: Update the frontmatter handling around the loop that
scans `lines[1:]` to first confirm a closing `---` delimiter was found; if the
block is unterminated, return without modifying or writing the document. Only
update or insert `last-active` after confirmed frontmatter closure, and add a
regression test covering a `CLAUDE.md` that starts with `---` but has no closing
delimiter.

In `@plugins/workspace/skills/handoff/SKILL.md`:
- Line 4: Update the argument hint for the handoff skill from [name-or-number]
to [name] so it reflects that handoff.py write resolves only project names and
not numeric indexes.

In `@plugins/workspace/tests/test_handoff.py`:
- Around line 258-295: Add a TestClear case covering a malformed marker with a
project filter: create the demo project, write invalid JSON to handoff.json, run
clear with --project demo, and assert the response reports deleted true and the
marker no longer exists. Keep the existing valid-marker and nonmatching-project
tests unchanged.

In `@plugins/workspace/tests/test_recent_projects.py`:
- Around line 229-230: In the test logic containing the status_idx and la_idx
searches, rename the enumerate loop variable from l to line and update both
startswith checks accordingly, preserving the existing behavior and PEP 8
readability.